Canterbury Books LMS - System Requirements (End User)
======================================================

Everything a PC (sections 1-6) or an Android phone/tablet (section 7) needs
to install and run Canterbury Books LMS. No developer tools, no Flutter SDK,
no Visual Studio - none of that is needed to run the app.

1. OPERATING SYSTEM
--------------------
- OS: Windows 10 (64-bit) version 1809 (build 17763) or later, or Windows 11.
  Older Windows 10 builds (still shipping the legacy "e" Edge) can install
  the app but CANNOT show books inside it - update Windows first.
- Architecture: x64 (Intel/AMD 64-bit). Not supported on ARM or 32-bit Windows
- Updates: Windows Update reasonably current (avoids missing OS-level components)
- User account: Any standard user account - NO administrator rights required
  (per-user install)

2. HARDWARE
-----------
- CPU: Any 64-bit CPU from the last ~10 years
- RAM: 4 GB minimum (8 GB recommended for smooth multitasking)
- Disk space: ~500 MB for the app itself, plus extra space for downloaded
  book files (varies by library size)
- Display: 1280x720 or higher
- Graphics: a working graphics card DRIVER with Direct3D 11 (any Intel/AMD/
  NVIDIA GPU from the last ~10 years). The in-app book reader draws pages
  through Windows Graphics Capture + Direct3D, so it CANNOT show books when:
    * Device Manager > Display adapters shows "Microsoft Basic Display
      Adapter" (no real driver installed) - install the PC maker's or
      Intel/AMD/NVIDIA's driver;
    * the app is used over Remote Desktop, inside a virtual machine, or on
      a terminal-server/thin-client session;
    * dxdiag > Display tab shows "Direct3D Acceleration: Not Available".
  The rest of the app (login, library, downloads) still works on such PCs.
  Seen in the field: Windows 10 Pro 22H2 (build 19045) with WebView2
  installed still failed for this reason - the Windows version alone is
  not enough.
- Network: Internet connection (Wi-Fi or Ethernet) - required for the FIRST
  login on each PC, syncing, and downloading books. After that, see
  "OFFLINE SIGN-IN" below.

3. SOFTWARE / RUNTIME COMPONENTS
---------------------------------
These are normally handled automatically - listed here so IT staff know
what the installer touches if anything looks unusual.

- Visual C++ Redistributable (2015-2022, x64)
  Needed for: running the app's native engine (msvcp140.dll, vcruntime140.dll)
  How provided: bundled inside the installer automatically. If somehow
  missing, the installer detects it and installs it silently during setup
  (needs internet at that moment).

- Microsoft Edge WebView2 Runtime
  Needed for: in-app web content rendering
  How provided: installed automatically by the setup wizard when missing
  (needs internet at that moment). Usually already present on up-to-date
  Windows 10/11. WITHOUT IT NO BOOK CAN OPEN ("Could not open this book").
  Manual install / offline machines:
  https://developer.microsoft.com/microsoft-edge/webview2/ (Evergreen
  Standalone Installer x64).

- .NET / other runtimes
  Not required - the app does not depend on .NET Framework or .NET Core

4. OS-LEVEL TOOLS/FEATURES THAT MUST BE ENABLED
-------------------------------------------------
- Windows Installer service (msiserver)
  Why: runs the setup wizard. Enabled by default on all Windows installs.

- TLS 1.2+
  Why: secure connection to the LMS backend (https://canterbury.spacer-lms.com)
  Enabled by default on Win10/11; only an issue on very old/locked-down
  configurations.

- Local write access to %LOCALAPPDATA%
  Why: where the app installs and stores downloaded books. Always available
  to a standard user account.

- Firewall must allow outbound HTTPS (port 443)
  Why: app login / book sync / downloads. School/corporate firewalls that
  block outbound HTTPS will break login and downloads even if the app
  installs fine.

- Windows must itself report "Connected" / internet access
  Why: the app currently asks WINDOWS whether the PC is online, instead of
  testing the connection itself. Windows decides this by quietly loading
  http://www.msftconnecttest.com/connecttest.txt (the "NCSI" check). If a
  school/corporate proxy, firewall, or Group Policy blocks that check,
  Windows shows a globe icon / "No internet" on the taskbar network icon
  even though the browser works - and the app then treats the PC as
  OFFLINE (login goes to offline mode, downloads don't start).
  Fix for IT: allow www.msftconnecttest.com and ipv6.msftconnecttest.com
  (HTTP, port 80) and dns.msftncsi.com, and make sure the Group Policy
  "Turn off Windows Network Connectivity Status Indicator active tests"
  is NOT enabled.

- Local write access to %APPDATA%
  Why: the encrypted file holding saved sign-ins for offline sign-in
  (see below). Always available to a standard user account.


OFFLINE SIGN-IN
----------------
Nothing extra to install - this works out of the box.

- A user must sign in ONLINE once on the PC. From that first sign-in they
  can sign in again WITHOUT internet (even after signing out) for
  3 months, using the same email/username and password. Signing in online
  again during those 3 months does NOT extend them; once the 3 months are
  up, the next online sign-in starts a new 3-month period.
- Offline, only books already downloaded on that PC can be read.
- When the internet comes back the app reconnects to the server by itself.
  If the password was changed in the meantime, the user is asked to sign
  in again.
- Where it is stored: an encrypted file (Windows DPAPI, tied to the
  Windows user account) at
  %APPDATA%\Canterbury Books LMS\Canterbury Books\flutter_secure_storage.dat
  Deleting it removes all saved offline sign-ins on that Windows account.
- SHARED PCs: the encryption protects the saved sign-ins from OTHER Windows
  accounts only. If several students share ONE Windows account, give each
  student their own Windows account where possible.


5. INSTALL STEPS
-----------------
1. Run CanterburyBooksLMS-Setup-<version>.exe
2. Follow the setup wizard (no admin password prompt)
3. Launch from the Start Menu or the desktop shortcut (if selected during
   install)

6. IF THE APP STILL WON'T OPEN
--------------------------------
- Error mentioning MSVCP140.dll or VCRUNTIME140.dll:
  Manually run https://aka.ms/vs/17/release/vc_redist.x64.exe, then
  relaunch the app.

- Error mentioning WebView2:
  Install from https://developer.microsoft.com/microsoft-edge/webview2/

- Login/sync fails but app opens:
  Check the network/firewall allows outbound HTTPS to
  canterbury.spacer-lms.com

- App says "Offline" / "You're offline" although the internet works:
  Look at the taskbar network icon. If it shows a globe or "No internet",
  Windows' own connectivity check is blocked - see "Windows must itself
  report Connected" in section 4. Quick confirmation: connect the PC to a
  phone hotspot; if the app is online there, it is the network, not the PC.

- Every book fails with "Could not open this book" on one PC (other PCs
  fine, WebView2 installed): almost always graphics - check the "Graphics"
  line in section 2 (Basic Display Adapter, Remote Desktop, or VM). The
  diagnostic log will contain "unsupported_platform". Installing the
  proper graphics driver, or using the PC locally instead of over Remote
  Desktop, fixes it.

- "Could not open this book" / any other problem - send the diagnostic log:
  %APPDATA%\Canterbury Books LMS\Canterbury Books\logs\app.log
  (and app.log.1 if present). Paste the path into File Explorer's address
  bar. The first line of each session shows the app version and the
  Windows build. The log holds no passwords or tokens.


7. ANDROID PHONES & TABLETS
----------------------------
- Android version: Android 7.0 (Nougat) or later. Android 8.0/8.1 and other
  phones with little memory work, but see "RAM" below.
- Architecture: any normal Android phone/tablet (ARM 32-bit, ARM 64-bit or
  x86_64).
- RAM: 2 GB minimum, 3 GB or more recommended. Books are image-heavy pages
  shown in the system WebView. On low-memory phones Android may stop the
  WebView while reading; the app then reopens the book by itself on the
  same page. If that keeps happening the reader shows "This device ran out
  of memory while showing the book" - close other apps and try again.
- Disk space: ~150 MB free for the app itself, plus space for downloaded
  books (varies by library size).
- Android System WebView (or Google Chrome on Android 7-9): REQUIRED to show
  books. It is preinstalled, but on older phones it is often years out of
  date, which makes books slow and more likely to run out of memory.
  Update "Android System WebView" (and "Google Chrome") from the Play Store
  before reporting a reader problem. It must not be disabled under
  Settings > Apps.
- Google Play services: NOT required.
- Permissions: Internet only. The app does not ask for storage, camera,
  location, or contacts permissions. Downloaded books are kept in the app's
  private storage and are removed when the app is uninstalled.
- Screen lock: recommended. Saved sign-ins for offline sign-in are
  encrypted with the Android Keystore.
- Network: same as the PC - Internet for the first sign-in, syncing and
  downloading books; outbound HTTPS (port 443) to canterbury.spacer-lms.com.
  Offline sign-in works the same way as on the PC (see "OFFLINE SIGN-IN").
  Saved sign-ins are NOT copied to a new phone by Android backup; sign in
  online once on the new phone.

Install (APK, outside the Play Store):
1. Copy CanterburyBooksLMS-<version>.apk to the phone (or download it).
2. Open it. When asked, allow "Install unknown apps" for the app you opened
   it from (Files / Chrome).
3. Tap Install, then Open.

If the app closes by itself while reading (seen on Android 8):
- Update the app - version 1.0.2 and older were closed by Android when the
  WebView ran out of memory; newer versions recover and reopen the book.
- Update "Android System WebView" and "Google Chrome" from the Play Store.
- Close other apps / restart the phone to free memory.
- Still happening: connect the phone to a PC with USB debugging enabled and
  send IT the output of
    adb logcat -d > reader-crash.txt
  captured right after the app closes. (The app's own diagnostic log,
  files/logs/app.log, is in private storage and cannot be copied off the
  phone without a debug build.)
